From a710e64bad599450ed071fce67c071c0f53b34b1 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 27 Feb 2021 10:54:47 -0500 Subject: [PATCH] printeroperation: Convert docs --- gtk/gtkprintoperation.c | 801 +++++++++++++++++++++------------------- gtk/gtkprintoperation.h | 9 +- 2 files changed, 426 insertions(+), 384 deletions(-) diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c index 382d461fec..c9773aa6f4 100644 --- a/gtk/gtkprintoperation.c +++ b/gtk/gtkprintoperation.c @@ -34,35 +34,33 @@ #include "gtktypebuiltins.h" /** - * SECTION:gtkprintoperation - * @Title: GtkPrintOperation - * @Short_description: High-level Printing API - * @See_also: #GtkPrintContext, #GtkPrintUnixDialog + * GtkPrintOperation: + * + * `GtkPrintOperation` is the high-level, portable printing API. * - * GtkPrintOperation is the high-level, portable printing API. * It looks a bit different than other GTK dialogs such as the - * #GtkFileChooser, since some platforms don’t expose enough + * `GtkFileChooser`, since some platforms don’t expose enough * infrastructure to implement a good print dialog. On such - * platforms, GtkPrintOperation uses the native print dialog. + * platforms, `GtkPrintOperation` uses the native print dialog. * On platforms which do not provide a native print dialog, GTK - * uses its own, see #GtkPrintUnixDialog. + * uses its own, see [class@Gtk.PrintUnixDialog]. * * The typical way to use the high-level printing API is to create - * a GtkPrintOperation object with gtk_print_operation_new() when - * the user selects to print. Then you set some properties on it, - * e.g. the page size, any #GtkPrintSettings from previous print + * a `GtkPrintOperation` object with [ctor@Gtk.PrintOperation.new] + * when the user selects to print. Then you set some properties on it, + * e.g. the page size, any [class@Gtk.PrintSettings] from previous print * operations, the number of pages, the current page, etc. * - * Then you start the print operation by calling gtk_print_operation_run(). - * It will then show a dialog, let the user select a printer and - * options. When the user finished the dialog various signals will - * be emitted on the #GtkPrintOperation, the main one being - * #GtkPrintOperation::draw-page, which you are supposed to catch - * and render the page on the provided #GtkPrintContext using Cairo. + * Then you start the print operation by calling [method@Gtk.PrintOperation.run]. + * It will then show a dialog, let the user select a printer and options. + * When the user finished the dialog, various signals will be emitted on + * the `GtkPrintOperation`, the main one being + * [signal@Gtk.PrintOperation::draw-page], which you are supposed to handle + * and render the page on the provided [class@Gtk.PrintContext] using Cairo. * * # The high-level printing API * - * |[ + * ```c * static GtkPrintSettings *settings = NULL; * * static void @@ -91,14 +89,14 @@ * * g_object_unref (print); * } - * ]| + * ``` * - * By default GtkPrintOperation uses an external application to do + * By default `GtkPrintOperation` uses an external application to do * print preview. To implement a custom print preview, an application * must connect to the preview signal. The functions - * gtk_print_operation_preview_render_page(), - * gtk_print_operation_preview_end_preview() and - * gtk_print_operation_preview_is_selected() + * [method@Gtk.PrintOperationPreview.render_page], + * [method@Gtk.PrintOperationPreview.end_preview] and + * [method@Gtk.PrintOperationPreview.is_selected] * are useful when implementing a print preview. */ @@ -165,9 +163,9 @@ G_DEFINE_TYPE_WITH_CODE (GtkPrintOperation, gtk_print_operation, G_TYPE_OBJECT, /** * gtk_print_error_quark: * - * Registers an error quark for #GtkPrintOperation if necessary. + * Registers an error quark for `GtkPrintOperation` if necessary. * - * Returns: The error quark used for #GtkPrintOperation errors. + * Returns: The error quark used for `GtkPrintOperation` errors. **/ GQuark gtk_print_error_quark (void) @@ -754,19 +752,19 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::done: - * @operation: the #GtkPrintOperation on which the signal was emitted + * @operation: the `GtkPrintOperation` on which the signal was emitted * @result: the result of the print operation * * Emitted when the print operation run has finished doing - * everything required for printing. + * everything required for printing. * - * @result gives you information about what happened during the run. + * @result gives you information about what happened during the run. * If @result is %GTK_PRINT_OPERATION_RESULT_ERROR then you can call - * gtk_print_operation_get_error() for more information. + * [method@Gtk.PrintOperation.get_error] for more information. * - * If you enabled print status tracking then - * gtk_print_operation_is_finished() may still return %FALSE - * after #GtkPrintOperation::done was emitted. + * If you enabled print status tracking then + * [method@Gtk.PrintOperation.is_finished] may still return %FALSE + * after the ::done signal was emitted. */ signals[DONE] = g_signal_new (I_("done"), @@ -779,15 +777,16 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::begin-print: - * @operation: the #GtkPrintOperation on which the signal was emitted - * @context: the #GtkPrintContext for the current operation + * @operation: the `GtkPrintOperation` on which the signal was emitted + * @context: the `GtkPrintContext` for the current operation * * Emitted after the user has finished changing print settings - * in the dialog, before the actual rendering starts. + * in the dialog, before the actual rendering starts. * * A typical use for ::begin-print is to use the parameters from the - * #GtkPrintContext and paginate the document accordingly, and then - * set the number of pages with gtk_print_operation_set_n_pages(). + * [class@Gtk.PrintContext] and paginate the document accordingly, + * and then set the number of pages with + * [method@Gtk.PrintOperation.set_n_pages]. */ signals[BEGIN_PRINT] = g_signal_new (I_("begin-print"), @@ -800,17 +799,18 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::paginate: - * @operation: the #GtkPrintOperation on which the signal was emitted - * @context: the #GtkPrintContext for the current operation + * @operation: the `GtkPrintOperation` on which the signal was emitted + * @context: the `GtkPrintContext` for the current operation + * + * Emitted after the ::begin-print signal, but before the actual rendering + * starts. * - * Emitted after the #GtkPrintOperation::begin-print signal, but before - * the actual rendering starts. It keeps getting emitted until a connected - * signal handler returns %TRUE. + * It keeps getting emitted until a connected signal handler returns %TRUE. * * The ::paginate signal is intended to be used for paginating a document * in small chunks, to avoid blocking the user interface for a long * time. The signal handler should update the number of pages using - * gtk_print_operation_set_n_pages(), and return %TRUE if the document + * [method@Gtk.PrintOperation.set_n_pages], and return %TRUE if the document * has been completely paginated. * * If you don't need to do pagination in chunks, you can simply do @@ -831,14 +831,16 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::request-page-setup: - * @operation: the #GtkPrintOperation on which the signal was emitted - * @context: the #GtkPrintContext for the current operation + * @operation: the `GtkPrintOperation` on which the signal was emitted + * @context: the `GtkPrintContext` for the current operation * @page_nr: the number of the currently printed page (0-based) - * @setup: the #GtkPageSetup - * - * Emitted once for every page that is printed, to give - * the application a chance to modify the page setup. Any changes - * done to @setup will be in force only for printing this page. + * @setup: the `GtkPageSetup` + * + * Emitted once for every page that is printed. + * + * This gives the application a chance to modify the page setup. + * Any changes done to @setup will be in force only for printing + * this page. */ signals[REQUEST_PAGE_SETUP] = g_signal_new (I_("request-page-setup"), @@ -854,14 +856,17 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::draw-page: - * @operation: the #GtkPrintOperation on which the signal was emitted - * @context: the #GtkPrintContext for the current operation + * @operation: the `GtkPrintOperation` on which the signal was emitted + * @context: the `GtkPrintContext` for the current operation * @page_nr: the number of the currently printed page (0-based) * - * Emitted for every page that is printed. The signal handler - * must render the @page_nr's page onto the cairo context obtained - * from @context using gtk_print_context_get_cairo_context(). - * |[ + * Emitted for every page that is printed. + * + * The signal handler must render the @page_nr's page onto the cairo + * context obtained from @context using + * [method@Gtk.PrintContext.get_cairo_context]. + * + * ```c * static void * draw_page (GtkPrintOperation *operation, * GtkPrintContext *context, @@ -900,12 +905,12 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) * * g_object_unref (layout); * } - * ]| + * ``` * - * Use gtk_print_operation_set_use_full_page() and - * gtk_print_operation_set_unit() before starting the print operation - * to set up the transformation of the cairo context according to your - * needs. + * Use [method@Gtk.PrintOperation.set_use_full_page] and + * [method@Gtk.PrintOperation.set_unit] before starting the print + * operation to set up the transformation of the cairo context + * according to your needs. */ signals[DRAW_PAGE] = g_signal_new (I_("draw-page"), @@ -920,12 +925,13 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::end-print: - * @operation: the #GtkPrintOperation on which the signal was emitted - * @context: the #GtkPrintContext for the current operation + * @operation: the `GtkPrintOperation` on which the signal was emitted + * @context: the `GtkPrintContext` for the current operation + * + * Emitted after all pages have been rendered. * - * Emitted after all pages have been rendered. * A handler for this signal can clean up any resources that have - * been allocated in the #GtkPrintOperation::begin-print handler. + * been allocated in the [signal@Gtk.PrintOperation::begin-print] handler. */ signals[END_PRINT] = g_signal_new (I_("end-print"), @@ -938,11 +944,12 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::status-changed: - * @operation: the #GtkPrintOperation on which the signal was emitted + * @operation: the `GtkPrintOperation` on which the signal was emitted * * Emitted at between the various phases of the print operation. - * See #GtkPrintStatus for the phases that are being discriminated. - * Use gtk_print_operation_get_status() to find out the current + * + * See [enum@Gtk.PrintStatus] for the phases that are being discriminated. + * Use [method@Gtk.PrintOperation.get_status] to find out the current * status. */ signals[STATUS_CHANGED] = @@ -957,21 +964,22 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::create-custom-widget: - * @operation: the #GtkPrintOperation on which the signal was emitted + * @operation: the `GtkPrintOperation` on which the signal was emitted + * + * Emitted when displaying the print dialog. * - * Emitted when displaying the print dialog. If you return a - * widget in a handler for this signal it will be added to a custom - * tab in the print dialog. You typically return a container widget - * with multiple widgets in it. + * If you return a widget in a handler for this signal it will be + * added to a custom tab in the print dialog. You typically return a + * container widget with multiple widgets in it. * - * The print dialog owns the returned widget, and its lifetime is not - * controlled by the application. However, the widget is guaranteed - * to stay around until the #GtkPrintOperation::custom-widget-apply - * signal is emitted on the operation. Then you can read out any + * The print dialog owns the returned widget, and its lifetime is not + * controlled by the application. However, the widget is guaranteed + * to stay around until the [signal@Gtk.PrintOperation::custom-widget-apply] + * signal is emitted on the operation. Then you can read out any * information you need from the widgets. * * Returns: (transfer none): A custom widget that gets embedded in - * the print dialog, or %NULL + * the print dialog, or %NULL */ signals[CREATE_CUSTOM_WIDGET] = g_signal_new (I_("create-custom-widget"), @@ -984,14 +992,15 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::update-custom-widget: - * @operation: the #GtkPrintOperation on which the signal was emitted - * @widget: the custom widget added in create-custom-widget + * @operation: the `GtkPrintOperation` on which the signal was emitted + * @widget: the custom widget added in ::create-custom-widget * @setup: actual page setup * @settings: actual print settings * - * Emitted after change of selected printer. The actual page setup and - * print settings are passed to the custom widget, which can actualize - * itself according to this change. + * Emitted after change of selected printer. + * + * The actual page setup and print settings are passed to the custom + * widget, which can actualize itself according to this change. */ signals[UPDATE_CUSTOM_WIDGET] = g_signal_new (I_("update-custom-widget"), @@ -1004,13 +1013,14 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::custom-widget-apply: - * @operation: the #GtkPrintOperation on which the signal was emitted - * @widget: the custom widget added in create-custom-widget + * @operation: the `GtkPrintOperation` on which the signal was emitted + * @widget: the custom widget added in ::create-custom-widget + * + * Emitted right before ::begin-print if you added + * a custom widget in the ::create-custom-widget handler. * - * Emitted right before #GtkPrintOperation::begin-print if you added - * a custom widget in the #GtkPrintOperation::create-custom-widget handler. - * When you get this signal you should read the information from the - * custom widgets, as the widgets are not guaraneed to be around at a + * When you get this signal you should read the information from the + * custom widgets, as the widgets are not guaranteed to be around at a * later time. */ signals[CUSTOM_WIDGET_APPLY] = @@ -1024,26 +1034,27 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * GtkPrintOperation::preview: - * @operation: the #GtkPrintOperation on which the signal was emitted - * @preview: the #GtkPrintOperationPreview for the current operation - * @context: the #GtkPrintContext that will be used - * @parent: (allow-none): the #GtkWindow to use as window parent, or %NULL + * @operation: the `GtkPrintOperation` on which the signal was emitted + * @preview: the `GtkPrintOperationPreview` for the current operation + * @context: the `GtkPrintContext` that will be used + * @parent: (allow-none): the `GtkWindow` to use as window parent, or %NULL * * Gets emitted when a preview is requested from the native dialog. * - * The default handler for this signal uses an external viewer + * The default handler for this signal uses an external viewer * application to preview. * * To implement a custom print preview, an application must return * %TRUE from its handler for this signal. In order to use the * provided @context for the preview implementation, it must be - * given a suitable cairo context with gtk_print_context_set_cairo_context(). - * - * The custom preview implementation can use - * gtk_print_operation_preview_is_selected() and - * gtk_print_operation_preview_render_page() to find pages which + * given a suitable cairo context with + * [method@Gtk.PrintContext.set_cairo_context]. + * + * The custom preview implementation can use + * [method@Gtk.PrintOperationPreview.is_selected] and + * [method@Gtk.PrintOperationPreview.render_page] to find pages which * are selected for print and render them. The preview must be - * finished by calling gtk_print_operation_preview_end_preview() + * finished by calling [method@Gtk.PrintOperationPreview.end_preview] * (typically in response to the user clicking a close button). * * Returns: %TRUE if the listener wants to take over control of the preview @@ -1060,15 +1071,14 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) GTK_TYPE_PRINT_CONTEXT, GTK_TYPE_WINDOW); - /** - * GtkPrintOperation:default-page-setup: + * GtkPrintOperation:default-page-setup: (attributes org.gtk.Property.get=gtk_print_operation_get_default_page_setup org.gtk.Property.set=gtk_print_operation_set_default_page_setup) * - * The #GtkPageSetup used by default. - * - * This page setup will be used by gtk_print_operation_run(), + * The `GtkPageSetup` used by default. + * + * This page setup will be used by [method@Gtk.PrintOperation.run], * but it can be overridden on a per-page basis by connecting - * to the #GtkPrintOperation::request-page-setup signal. + * to the [signal@Gtk.PrintOperation::request-page-setup] signal. */ g_object_class_install_property (gobject_class, PROP_DEFAULT_PAGE_SETUP, @@ -1079,13 +1089,13 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) GTK_PARAM_READWRITE)); /** - * GtkPrintOperation:print-settings: + * GtkPrintOperation:print-settings: (attributes org.gtk.Property.get=gtk_print_operation_get_print_settings org.gtk.Property.set=gtk_print_operation_set_print_settings) * - * The #GtkPrintSettings used for initializing the dialog. + * The `GtkPrintSettings` used for initializing the dialog. * - * Setting this property is typically used to re-establish - * print settings from a previous print operation, see - * gtk_print_operation_run(). + * Setting this property is typically used to re-establish + * print settings from a previous print operation, see + * [method@Gtk.PrintOperation.run]. */ g_object_class_install_property (gobject_class, PROP_PRINT_SETTINGS, @@ -1094,14 +1104,14 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) P_("The GtkPrintSettings used for initializing the dialog"), GTK_TYPE_PRINT_SETTINGS, GTK_PARAM_READWRITE)); - + /** - * GtkPrintOperation:job-name: + * GtkPrintOperation:job-name: (attributes org.gtk.Property.set=gtk_print_operation_set_job_name) + * + * A string used to identify the job (e.g. in monitoring + * applications like eggcups). * - * A string used to identify the job (e.g. in monitoring - * applications like eggcups). - * - * If you don't set a job name, GTK picks a default one + * If you don't set a job name, GTK picks a default one * by numbering successive print jobs. */ g_object_class_install_property (gobject_class, @@ -1113,18 +1123,18 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) GTK_PARAM_READWRITE)); /** - * GtkPrintOperation:n-pages: + * GtkPrintOperation:n-pages: (attributes org.gtk.Property.set=gtk_print_operation_set_n_pages) * - * The number of pages in the document. + * The number of pages in the document. * - * This must be set to a positive number - * before the rendering starts. It may be set in a - * #GtkPrintOperation::begin-print signal handler. + * This must be set to a positive number before the rendering + * starts. It may be set in a [signal@Gtk.PrintOperation::begin-print] + * signal handler. * - * Note that the page numbers passed to the - * #GtkPrintOperation::request-page-setup and - * #GtkPrintOperation::draw-page signals are 0-based, i.e. if - * the user chooses to print all pages, the last ::draw-page signal + * Note that the page numbers passed to the + * [signal@Gtk.PrintOperation::request-page-setup] and + * [signal@Gtk.PrintOperation::draw-page] signals are 0-based, i.e. + * if the user chooses to print all pages, the last ::draw-page signal * will be for page @n_pages - 1. */ g_object_class_install_property (gobject_class, @@ -1138,11 +1148,11 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); /** - * GtkPrintOperation:current-page: + * GtkPrintOperation:current-page: (attributes org.gtk.Property.set=gtk_print_operation_set_current_page) * * The current page in the document. * - * If this is set before gtk_print_operation_run(), + * If this is set before [method@Gtk.PrintOperation.run], * the user will be able to select to print only the current page. * * Note that this only makes sense for pre-paginated documents. @@ -1156,16 +1166,18 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) G_MAXINT, -1, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); - + /** - * GtkPrintOperation:use-full-page: - * - * If %TRUE, the transformation for the cairo context obtained - * from #GtkPrintContext puts the origin at the top left corner - * of the page (which may not be the top left corner of the sheet, - * depending on page orientation and the number of pages per sheet). - * Otherwise, the origin is at the top left corner of the imageable - * area (i.e. inside the margins). + * GtkPrintOperation:use-full-page: (attributes org.gtk.Property.set=gtk_print_operation_set_use_full_page) + * + * If %TRUE, the transformation for the cairo context obtained + * from `GtkPrintContext` puts the origin at the top left corner + * of the page. + * + * This may not be the top left corner of the sheet, depending on + * page orientation and the number of pages per sheet. Otherwise, + * the origin is at the top left corner of the imageable area (i.e. + * inside the margins). */ g_object_class_install_property (gobject_class, PROP_USE_FULL_PAGE, @@ -1174,16 +1186,16 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) P_("TRUE if the origin of the context should be at the corner of the page and not the corner of the imageable area"), FALSE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); - /** - * GtkPrintOperation:track-print-status: + * GtkPrintOperation:track-print-status: (attributes org.gtk.Property.set=gtk_print_operation_set_track_print_status) * - * If %TRUE, the print operation will try to continue report on - * the status of the print job in the printer queues and printer. - * This can allow your application to show things like “out of paper” - * issues, and when the print job actually reaches the printer. - * However, this is often implemented using polling, and should + * If %TRUE, the print operation will try to continue report on + * the status of the print job in the printer queues and printer. + * + * This can allow your application to show things like “out of paper” + * issues, and when the print job actually reaches the printer. + * However, this is often implemented using polling, and should * not be enabled unless needed. */ g_object_class_install_property (gobject_class, @@ -1193,13 +1205,12 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) P_("TRUE if the print operation will continue to report on the print job status after the print data has been sent to the printer or print server."), FALSE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); - /** - * GtkPrintOperation:unit: + * GtkPrintOperation:unit: (attributes org.gtk.Property.set=gtk_print_operation_set_unit) * * The transformation for the cairo context obtained from - * #GtkPrintContext is set up in such a way that distances + * `GtkPrintContext` is set up in such a way that distances * are measured in units of @unit. */ g_object_class_install_property (gobject_class, @@ -1210,12 +1221,11 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) GTK_TYPE_UNIT, GTK_UNIT_NONE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); - - + /** - * GtkPrintOperation:show-progress: + * GtkPrintOperation:show-progress: (attributes org.gtk.Property.set=gtk_print_operation_set_show_progress) * - * Determines whether to show a progress dialog during the + * Determines whether to show a progress dialog during the * print operation. */ g_object_class_install_property (gobject_class, @@ -1227,17 +1237,17 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); /** - * GtkPrintOperation:allow-async: + * GtkPrintOperation:allow-async: (attributes org.gtk.Property.set=gtk_print_operation_set_allow_async) * * Determines whether the print operation may run asynchronously or not. * * Some systems don't support asynchronous printing, but those that do * will return %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS as the status, and - * emit the #GtkPrintOperation::done signal when the operation is actually - * done. + * emit the [signal@Gtk.PrintOperation::done] signal when the operation + * is actually done. * - * The Windows port does not support asynchronous operation at all (this - * is unlikely to change). On other platforms, all actions except for + * The Windows port does not support asynchronous operation at all (this + * is unlikely to change). On other platforms, all actions except for * %GTK_PRINT_OPERATION_ACTION_EXPORT support asynchronous operation. */ g_object_class_install_property (gobject_class, @@ -1247,18 +1257,19 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) P_("TRUE if print process may run asynchronous."), FALSE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); - + /** - * GtkPrintOperation:export-filename: + * GtkPrintOperation:export-filename: (attributes org.gtk.Property.set=gtk_print_operation_set_export_filename) + * + * The name of a file to generate instead of showing the print dialog. * - * The name of a file to generate instead of showing the print dialog. * Currently, PDF is the only supported format. * - * The intended use of this property is for implementing + * The intended use of this property is for implementing * “Export to PDF” actions. * * “Print to PDF” support is independent of this and is done - * by letting the user pick the “Print to PDF” item from the + * by letting the user pick the “Print to PDF” item from the * list of printers in the print dialog. */ g_object_class_install_property (gobject_class, @@ -1268,9 +1279,9 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) P_("Export filename"), NULL, GTK_PARAM_READWRITE)); - + /** - * GtkPrintOperation:status: + * GtkPrintOperation:status: (attributes org.gtk.Property.get=gtk_print_operation_get_status) * * The status of the print operation. */ @@ -1282,16 +1293,17 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) GTK_TYPE_PRINT_STATUS, GTK_PRINT_STATUS_INITIAL, GTK_PARAM_READABLE|G_PARAM_EXPLICIT_NOTIFY)); - + /** - * GtkPrintOperation:status-string: + * GtkPrintOperation:status-string: (attributes org.gtk.Property.get=gtk_print_operation_get_status_string) * - * A string representation of the status of the print operation. - * The string is translated and suitable for displaying the print - * status e.g. in a #GtkStatusbar. + * A string representation of the status of the print operation. * - * See the #GtkPrintOperation:status property for a status value that - * is suitable for programmatic use. + * The string is translated and suitable for displaying the print + * status e.g. in a `GtkStatusbar`. + * + * See the [property@Gtk.PrintOperation:status] property for a status + * value that is suitable for programmatic use. */ g_object_class_install_property (gobject_class, PROP_STATUS_STRING, @@ -1303,11 +1315,12 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** - * GtkPrintOperation:custom-tab-label: + * GtkPrintOperation:custom-tab-label: (attributes org.gtk.Property.set=gtk_print_operation_set_custom_tab_label) * * Used as the label of the tab containing custom widgets. + * * Note that this property may be ignored on some platforms. - * + * * If this is %NULL, GTK uses a default label. */ g_object_class_install_property (gobject_class, @@ -1319,9 +1332,10 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) GTK_PARAM_READWRITE)); /** - * GtkPrintOperation:support-selection: + * GtkPrintOperation:support-selection: (attributes org.gtk.Property.get=gtk_print_operation_get_support_selection org.gtk.Property.set=gtk_print_operation_set_support_selection) * * If %TRUE, the print operation will support print of selection. + * * This allows the print dialog to show a "Selection" button. */ g_object_class_install_property (gobject_class, @@ -1333,9 +1347,10 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); /** - * GtkPrintOperation:has-selection: + * GtkPrintOperation:has-selection: (attributes org.gtk.Property.get=gtk_print_operation_get_has_selection org.gtk.Property.set=gtk_print_operation_set_has_selection) * * Determines whether there is a selection in your application. + * * This can allow your application to print the selection. * This is typically used to make a "Selection" button sensitive. */ @@ -1349,9 +1364,10 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** - * GtkPrintOperation:embed-page-setup: + * GtkPrintOperation:embed-page-setup: (attributes org.gtk.Property.get=gtk_print_operation_get_embed_page_setup org.gtk.Property.set=gtk_print_operation_set_embed_page_setup) * - * If %TRUE, page size combo box and orientation combo box are embedded into page setup page. + * If %TRUE, page size combo box and orientation combo box + * are embedded into page setup page. */ g_object_class_install_property (gobject_class, PROP_EMBED_PAGE_SETUP, @@ -1360,17 +1376,19 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) P_("TRUE if page setup combos are embedded in GtkPrintUnixDialog"), FALSE, GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY)); + /** - * GtkPrintOperation:n-pages-to-print: + * GtkPrintOperation:n-pages-to-print: (attributes org.gtk.Property.get=gtk_print_operation_get_n_pages_to_print) * * The number of pages that will be printed. * * Note that this value is set during print preparation phase * (%GTK_PRINT_STATUS_PREPARING), so this value should never be * get before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). - * You can connect to the #GtkPrintOperation::status-changed signal - * and call gtk_print_operation_get_n_pages_to_print() when + * You can connect to the [signal@Gtk.PrintOperation::status-changed] signal + * and call [method@Gtk.PrintOperation.get_n_pages_to_print] when * print status is %GTK_PRINT_STATUS_GENERATING_DATA. + * * This is typically used to track the progress of print operation. */ g_object_class_install_property (gobject_class, @@ -1387,9 +1405,9 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class) /** * gtk_print_operation_new: * - * Creates a new #GtkPrintOperation. + * Creates a new `GtkPrintOperation`. * - * Returns: a new #GtkPrintOperation + * Returns: a new `GtkPrintOperation` */ GtkPrintOperation * gtk_print_operation_new (void) @@ -1402,15 +1420,15 @@ gtk_print_operation_new (void) } /** - * gtk_print_operation_set_default_page_setup: - * @op: a #GtkPrintOperation - * @default_page_setup: (allow-none): a #GtkPageSetup, or %NULL + * gtk_print_operation_set_default_page_setup: (attributes org.gtk.Method.set_property=default-page-setup) + * @op: a `GtkPrintOperation` + * @default_page_setup: (allow-none): a `GtkPageSetup`, or %NULL * * Makes @default_page_setup the default page setup for @op. * - * This page setup will be used by gtk_print_operation_run(), + * This page setup will be used by [method@Gtk.PrintOperation.run], * but it can be overridden on a per-page basis by connecting - * to the #GtkPrintOperation::request-page-setup signal. + * to the [signal@Gtk.PrintOperation::request-page-setup] signal. **/ void gtk_print_operation_set_default_page_setup (GtkPrintOperation *op, @@ -1437,11 +1455,10 @@ gtk_print_operation_set_default_page_setup (GtkPrintOperation *op, } /** - * gtk_print_operation_get_default_page_setup: - * @op: a #GtkPrintOperation + * gtk_print_operation_get_default_page_setup: (attributes org.gtk.Method.get_property=default-page-setup) + * @op: a `GtkPrintOperation` * - * Returns the default page setup, see - * gtk_print_operation_set_default_page_setup(). + * Returns the default page setup. * * Returns: (transfer none): the default page setup */ @@ -1455,14 +1472,15 @@ gtk_print_operation_get_default_page_setup (GtkPrintOperation *op) /** - * gtk_print_operation_set_print_settings: - * @op: a #GtkPrintOperation - * @print_settings: (allow-none): #GtkPrintSettings + * gtk_print_operation_set_print_settings: (attributes org.gtk.Method.set_property=print-settings) + * @op: a `GtkPrintOperation` + * @print_settings: (allow-none): `GtkPrintSettings` * - * Sets the print settings for @op. This is typically used to - * re-establish print settings from a previous print operation, - * see gtk_print_operation_run(). - **/ + * Sets the print settings for @op. + * + * This is typically used to re-establish print settings + * from a previous print operation, see [method@Gtk.PrintOperation.run]. + */ void gtk_print_operation_set_print_settings (GtkPrintOperation *op, GtkPrintSettings *print_settings) @@ -1488,14 +1506,14 @@ gtk_print_operation_set_print_settings (GtkPrintOperation *op, } /** - * gtk_print_operation_get_print_settings: - * @op: a #GtkPrintOperation + * gtk_print_operation_get_print_settings: (attributes org.gtk.Method.get_property=print-settings) + * @op: a `GtkPrintOperation` * * Returns the current print settings. * * Note that the return value is %NULL until either - * gtk_print_operation_set_print_settings() or - * gtk_print_operation_run() have been called. + * [method@Gtk.PrintOperation.set_print_settings] or + * [method@Gtk.PrintOperation.run] have been called. * * Returns: (transfer none): the current print settings of @op. **/ @@ -1508,16 +1526,18 @@ gtk_print_operation_get_print_settings (GtkPrintOperation *op) } /** - * gtk_print_operation_set_job_name: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_job_name: (attributes org.gtk.Method.set_property=job-name) + * @op: a `GtkPrintOperation` * @job_name: a string that identifies the print job - * - * Sets the name of the print job. The name is used to identify - * the job (e.g. in monitoring applications like eggcups). - * - * If you don’t set a job name, GTK picks a default one by + * + * Sets the name of the print job. + * + * The name is used to identify the job (e.g. in monitoring + * applications like eggcups). + * + * If you don’t set a job name, GTK picks a default one by * numbering successive print jobs. - **/ + */ void gtk_print_operation_set_job_name (GtkPrintOperation *op, const char *job_name) @@ -1537,22 +1557,22 @@ gtk_print_operation_set_job_name (GtkPrintOperation *op, } /** - * gtk_print_operation_set_n_pages: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_n_pages: (attributes org.gtk.Method.set_property=n-pages) + * @op: a `GtkPrintOperation` * @n_pages: the number of pages - * - * Sets the number of pages in the document. * - * This must be set to a positive number - * before the rendering starts. It may be set in a - * #GtkPrintOperation::begin-print signal handler. + * Sets the number of pages in the document. + * + * This must be set to a positive number before the rendering + * starts. It may be set in a [signal@Gtk.PrintOperation::begin-print] + * signal handler. * - * Note that the page numbers passed to the - * #GtkPrintOperation::request-page-setup - * and #GtkPrintOperation::draw-page signals are 0-based, i.e. if - * the user chooses to print all pages, the last ::draw-page signal + * Note that the page numbers passed to the + * [signal@Gtk.PrintOperation::request-page-setup] + * and [signal@Gtk.PrintOperation::draw-page] signals are 0-based, i.e. + * if the user chooses to print all pages, the last ::draw-page signal * will be for page @n_pages - 1. - **/ + */ void gtk_print_operation_set_n_pages (GtkPrintOperation *op, int n_pages) @@ -1573,17 +1593,17 @@ gtk_print_operation_set_n_pages (GtkPrintOperation *op, } /** - * gtk_print_operation_set_current_page: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_current_page: (attributes org.gtk.Method.set_property=current-page) + * @op: a `GtkPrintOperation` * @current_page: the current page, 0-based * * Sets the current page. * - * If this is called before gtk_print_operation_run(), + * If this is called before [method@Gtk.PrintOperation.run], * the user will be able to select to print only the current page. * * Note that this only makes sense for pre-paginated documents. - **/ + */ void gtk_print_operation_set_current_page (GtkPrintOperation *op, int current_page) @@ -1604,16 +1624,17 @@ gtk_print_operation_set_current_page (GtkPrintOperation *op, } /** - * gtk_print_operation_set_use_full_page: - * @op: a #GtkPrintOperation - * @full_page: %TRUE to set up the #GtkPrintContext for the full page - * - * If @full_page is %TRUE, the transformation for the cairo context - * obtained from #GtkPrintContext puts the origin at the top left - * corner of the page (which may not be the top left corner of the - * sheet, depending on page orientation and the number of pages per - * sheet). Otherwise, the origin is at the top left corner of the - * imageable area (i.e. inside the margins). + * gtk_print_operation_set_use_full_page: (attributes org.gtk.Method.set_property=use-full-page) + * @op: a `GtkPrintOperation` + * @full_page: %TRUE to set up the `GtkPrintContext` for the full page + * + * If @full_page is %TRUE, the transformation for the cairo context + * obtained from `GtkPrintContext` puts the origin at the top left + * corner of the page. + * + * This may not be the top left corner of the sheet, depending on page + * orientation and the number of pages per sheet). Otherwise, the origin + * is at the top left corner of the imageable area (i.e. inside the margins). */ void gtk_print_operation_set_use_full_page (GtkPrintOperation *op, @@ -1634,12 +1655,12 @@ gtk_print_operation_set_use_full_page (GtkPrintOperation *op, } /** - * gtk_print_operation_set_unit: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_unit: (attributes org.gtk.Method.set_property=unit) + * @op: a `GtkPrintOperation` * @unit: the unit to use - * + * * Sets up the transformation for the cairo context obtained from - * #GtkPrintContext in such a way that distances are measured in + * `GtkPrintContext` in such a way that distances are measured in * units of @unit. */ void @@ -1659,17 +1680,18 @@ gtk_print_operation_set_unit (GtkPrintOperation *op, } /** - * gtk_print_operation_set_track_print_status: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_track_print_status: (attributes org.gtk.Method.set_property=track-print-status) + * @op: a `GtkPrintOperation` * @track_status: %TRUE to track status after printing - * - * If track_status is %TRUE, the print operation will try to continue report - * on the status of the print job in the printer queues and printer. This - * can allow your application to show things like “out of paper” issues, - * and when the print job actually reaches the printer. - * - * This function is often implemented using some form of polling, so it should - * not be enabled unless needed. + * + * If track_status is %TRUE, the print operation will try to continue + * report on the status of the print job in the printer queues and printer. + * + * This can allow your application to show things like “out of paper” + * issues, and when the print job actually reaches the printer. + * + * This function is often implemented using some form of polling, + * so it should not be enabled unless needed. */ void gtk_print_operation_set_track_print_status (GtkPrintOperation *op, @@ -1727,14 +1749,15 @@ _gtk_print_operation_set_status (GtkPrintOperation *op, /** - * gtk_print_operation_get_status: - * @op: a #GtkPrintOperation - * - * Returns the status of the print operation. - * Also see gtk_print_operation_get_status_string(). - * + * gtk_print_operation_get_status: (attributes org.gtk.Method.get_property=status) + * @op: a `GtkPrintOperation` + * + * Returns the status of the print operation. + * + * Also see [method@Gtk.PrintOperation.get_status_string]. + * * Returns: the status of the print operation - **/ + */ GtkPrintStatus gtk_print_operation_get_status (GtkPrintOperation *op) { @@ -1745,19 +1768,21 @@ gtk_print_operation_get_status (GtkPrintOperation *op) } /** - * gtk_print_operation_get_status_string: - * @op: a #GtkPrintOperation - * - * Returns a string representation of the status of the - * print operation. The string is translated and suitable - * for displaying the print status e.g. in a #GtkStatusbar. + * gtk_print_operation_get_status_string: (attributes org.gtk.Method.get_property=status-string) + * @op: a `GtkPrintOperation` + * + * Returns a string representation of the status of the + * print operation. + * + * The string is translated and suitable for displaying + * the print status e.g. in a `GtkStatusbar`. + * + * Use [method@Gtk.PrintOperation.get_status] to obtain + * a status value that is suitable for programmatic use. * - * Use gtk_print_operation_get_status() to obtain a status - * value that is suitable for programmatic use. - * * Returns: a string representation of the status * of the print operation - **/ + */ const char * gtk_print_operation_get_status_string (GtkPrintOperation *op) { @@ -1768,18 +1793,20 @@ gtk_print_operation_get_status_string (GtkPrintOperation *op) /** * gtk_print_operation_is_finished: - * @op: a #GtkPrintOperation - * + * @op: a `GtkPrintOperation` + * * A convenience function to find out if the print operation - * is finished, either successfully (%GTK_PRINT_STATUS_FINISHED) - * or unsuccessfully (%GTK_PRINT_STATUS_FINISHED_ABORTED). - * + * is finished. + * + * a print operation is finished if its status is either + * %GTK_PRINT_STATUS_FINISHED or %GTK_PRINT_STATUS_FINISHED_ABORTED. + * * Note: when you enable print status tracking the print operation * can be in a non-finished state even after done has been called, as * the operation status then tracks the print job status on the printer. - * + * * Returns: %TRUE, if the print operation is finished. - **/ + */ gboolean gtk_print_operation_is_finished (GtkPrintOperation *op) { @@ -1793,12 +1820,12 @@ gtk_print_operation_is_finished (GtkPrintOperation *op) } /** - * gtk_print_operation_set_show_progress: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_show_progress: (attributes org.gtk.Method.set_property=show-progress) + * @op: a `GtkPrintOperation` * @show_progress: %TRUE to show a progress dialog - * - * If @show_progress is %TRUE, the print operation will show a - * progress dialog during the print operation. + * + * If @show_progress is %TRUE, the print operation will show + * a progress dialog during the print operation. */ void gtk_print_operation_set_show_progress (GtkPrintOperation *op, @@ -1819,13 +1846,15 @@ gtk_print_operation_set_show_progress (GtkPrintOperation *op, } /** - * gtk_print_operation_set_allow_async: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_allow_async: (attributes org.gtk.Method.set_property=allow-async) + * @op: a `GtkPrintOperation` * @allow_async: %TRUE to allow asynchronous operation * - * Sets whether the gtk_print_operation_run() may return - * before the print operation is completed. Note that - * some platforms may not allow asynchronous operation. + * Sets whether gtk_print_operation_run() may return + * before the print operation is completed. + * + * Note that some platforms may not allow asynchronous + * operation. */ void gtk_print_operation_set_allow_async (GtkPrintOperation *op, @@ -1847,8 +1876,8 @@ gtk_print_operation_set_allow_async (GtkPrintOperation *op, /** - * gtk_print_operation_set_custom_tab_label: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_custom_tab_label: (attributes org.gtk.Method.set_property=custom-tab-label) + * @op: a `GtkPrintOperation` * @label: (allow-none): the label to use, or %NULL to use the default label * * Sets the label for the tab holding custom widgets. @@ -1869,14 +1898,16 @@ gtk_print_operation_set_custom_tab_label (GtkPrintOperation *op, /** - * gtk_print_operation_set_export_filename: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_export_filename: (attributes org.gtk.Method.set_property=export-filename) + * @op: a `GtkPrintOperation` * @filename: (type filename): the filename for the exported file - * - * Sets up the #GtkPrintOperation to generate a file instead - * of showing the print dialog. The intended use of this function - * is for implementing “Export to PDF” actions. Currently, PDF - * is the only supported format. + * + * Sets up the `GtkPrintOperation` to generate a file instead + * of showing the print dialog. + * + * The intended use of this function is for implementing + * “Export to PDF” actions. Currently, PDF is the only supported + * format. * * “Print to PDF” support is independent of this and is done * by letting the user pick the “Print to PDF” item from the list @@ -2253,14 +2284,16 @@ update_progress (PrintPagesData *data) /** * gtk_print_operation_set_defer_drawing: - * @op: a #GtkPrintOperation - * - * Sets up the #GtkPrintOperation to wait for calling of - * gtk_print_operation_draw_page_finish() from application. It can - * be used for drawing page in another thread. + * @op: a `GtkPrintOperation` * - * This function must be called in the callback of “draw-page” signal. - **/ + * Sets up the `GtkPrintOperation` to wait for calling of + * [method@Gtk.PrintOperation.draw_page_finish from application. + * + * This can be used for drawing page in another thread. + * + * This function must be called in the callback of the + * [signal@Gtk.PrintOperation::draw-page] signal. + */ void gtk_print_operation_set_defer_drawing (GtkPrintOperation *op) { @@ -2272,13 +2305,14 @@ gtk_print_operation_set_defer_drawing (GtkPrintOperation *op) } /** - * gtk_print_operation_set_embed_page_setup: - * @op: a #GtkPrintOperation - * @embed: %TRUE to embed page setup selection in the #GtkPrintUnixDialog + * gtk_print_operation_set_embed_page_setup: (attributes org.gtk.Method.set_property=embed-page-setup) + * @op: a `GtkPrintOperation` + * @embed: %TRUE to embed page setup selection in the `GtkPrintUnixDialog` * * Embed page size combo box and orientation combo box into page setup page. - * Selected page setup is stored as default page setup in #GtkPrintOperation. - **/ + * + * Selected page setup is stored as default page setup in `GtkPrintOperation`. + */ void gtk_print_operation_set_embed_page_setup (GtkPrintOperation *op, gboolean embed) @@ -2296,11 +2330,11 @@ gtk_print_operation_set_embed_page_setup (GtkPrintOperation *op, } /** - * gtk_print_operation_get_embed_page_setup: - * @op: a #GtkPrintOperation + * gtk_print_operation_get_embed_page_setup: (attributes org.gtk.Method.get_property=embed-page-setup) + * @op: a `GtkPrintOperation` + * + * Gets whether page setup selection combos are embedded * - * Gets the value of #GtkPrintOperation:embed-page-setup property. - * * Returns: whether page setup selection combos are embedded */ gboolean @@ -2315,16 +2349,15 @@ gtk_print_operation_get_embed_page_setup (GtkPrintOperation *op) /** * gtk_print_operation_draw_page_finish: - * @op: a #GtkPrintOperation - * - * Signalize that drawing of particular page is complete. + * @op: a `GtkPrintOperation` * - * It is called after completion of page drawing (e.g. drawing in another - * thread). - * If gtk_print_operation_set_defer_drawing() was called before, then this function - * has to be called by application. In another case it is called by the library - * itself. - **/ + * Signal that drawing of particular page is complete. + * + * It is called after completion of page drawing (e.g. drawing + * in another thread). If [method@Gtk.PrintOperation.set_defer_drawing] + * was called before, then this function has to be called by application. + * Otherwise it is called by GTK itself. + */ void gtk_print_operation_draw_page_finish (GtkPrintOperation *op) { @@ -2950,14 +2983,18 @@ print_pages (GtkPrintOperation *op, /** * gtk_print_operation_get_error: - * @op: a #GtkPrintOperation + * @op: a `GtkPrintOperation` * @error: return location for the error - * + * * Call this when the result of a print operation is - * %GTK_PRINT_OPERATION_RESULT_ERROR, either as returned by - * gtk_print_operation_run(), or in the #GtkPrintOperation::done signal - * handler. The returned #GError will contain more details on what went wrong. - **/ + * %GTK_PRINT_OPERATION_RESULT_ERROR. + * + * It can be called either after [method@Gtk.PrintOperation.run] + * returns, or in the [signal@Gtk.PrintOperation::done] signal + * handler. + * + * The returned `GError` will contain more details on what went wrong. + */ void gtk_print_operation_get_error (GtkPrintOperation *op, GError **error) @@ -2972,43 +3009,43 @@ gtk_print_operation_get_error (GtkPrintOperation *op, /** * gtk_print_operation_run: - * @op: a #GtkPrintOperation + * @op: a `GtkPrintOperation` * @action: the action to start * @parent: (allow-none): Transient parent of the dialog * @error: (allow-none): Return location for errors, or %NULL * - * Runs the print operation, by first letting the user modify - * print settings in the print dialog, and then print the document. + * Runs the print operation. + * + * Normally that this function does not return until the rendering + * of all pages is complete. You can connect to the + * [signal@Gtk.PrintOperation::status-changed] signal on @op to obtain + * some information about the progress of the print operation. * - * Normally that this function does not return until the rendering of all - * pages is complete. You can connect to the - * #GtkPrintOperation::status-changed signal on @op to obtain some - * information about the progress of the print operation. * Furthermore, it may use a recursive mainloop to show the print dialog. * - * If you call gtk_print_operation_set_allow_async() or set the - * #GtkPrintOperation:allow-async property the operation will run - * asynchronously if this is supported on the platform. The - * #GtkPrintOperation::done signal will be emitted with the result of the - * operation when the it is done (i.e. when the dialog is canceled, or when - * the print succeeds or fails). - * |[ + * If you set the [Gtk.PrintOperation:allow-async] property, the operation + * will run asynchronously if this is supported on the platform. The + * [signal@Gtk.PrintOperation::done] signal will be emitted with the result + * of the operation when the it is done (i.e. when the dialog is canceled, + * or when the print succeeds or fails). + * + * ```c * if (settings != NULL) * gtk_print_operation_set_print_settings (print, settings); - * + * * if (page_setup != NULL) * gtk_print_operation_set_default_page_setup (print, page_setup); - * - * g_signal_connect (print, "begin-print", + * + * g_signal_connect (print, "begin-print", * G_CALLBACK (begin_print), &data); - * g_signal_connect (print, "draw-page", + * g_signal_connect (print, "draw-page", * G_CALLBACK (draw_page), &data); - * - * res = gtk_print_operation_run (print, - * GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, - * parent, + * + * res = gtk_print_operation_run (print, + * GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, + * parent, * &error); - * + * * if (res == GTK_PRINT_OPERATION_RESULT_ERROR) * { * error_dialog = gtk_message_dialog_new (GTK_WINDOW (parent), @@ -3017,7 +3054,7 @@ gtk_print_operation_get_error (GtkPrintOperation *op, * GTK_BUTTONS_CLOSE, * "Error printing file:\n%s", * error->message); - * g_signal_connect (error_dialog, "response", + * g_signal_connect (error_dialog, "response", * G_CALLBACK (gtk_window_destroy), NULL); * gtk_widget_show (error_dialog); * g_error_free (error); @@ -3028,20 +3065,21 @@ gtk_print_operation_get_error (GtkPrintOperation *op, * g_object_unref (settings); * settings = g_object_ref (gtk_print_operation_get_print_settings (print)); * } - * ]| + * ``` * * Note that gtk_print_operation_run() can only be called once on a - * given #GtkPrintOperation. + * given `GtkPrintOperation`. * - * Returns: the result of the print operation. A return value of + * Returns: the result of the print operation. A return value of * %GTK_PRINT_OPERATION_RESULT_APPLY indicates that the printing was - * completed successfully. In this case, it is a good idea to obtain - * the used print settings with gtk_print_operation_get_print_settings() + * completed successfully. In this case, it is a good idea to obtain + * the used print settings with + * [method@Gtk.PrintOperation.get_print_settings] * and store them for reuse with the next print operation. A value of * %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS means the operation is running - * asynchronously, and will emit the #GtkPrintOperation::done signal when - * done. - **/ + * asynchronously, and will emit the [signal@Gtk.PrintOperation::done] + * signal when done. + */ GtkPrintOperationResult gtk_print_operation_run (GtkPrintOperation *op, GtkPrintOperationAction action, @@ -3128,13 +3166,13 @@ gtk_print_operation_run (GtkPrintOperation *op, /** * gtk_print_operation_cancel: - * @op: a #GtkPrintOperation + * @op: a `GtkPrintOperation` * - * Cancels a running print operation. This function may - * be called from a #GtkPrintOperation::begin-print, - * #GtkPrintOperation::paginate or #GtkPrintOperation::draw-page - * signal handler to stop the currently running print - * operation. + * Cancels a running print operation. + * + * This function may be called from a [signal@Gtk.PrintOperation::begin-print], + * [signal@Gtk.PrintOperation::paginate] or [signal@Gtk.PrintOperation::draw-page] + * signal handler to stop the currently running print operation. */ void gtk_print_operation_cancel (GtkPrintOperation *op) @@ -3145,11 +3183,11 @@ gtk_print_operation_cancel (GtkPrintOperation *op) } /** - * gtk_print_operation_set_support_selection: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_support_selection: (attributes org.gtk.Method.set_property=support-selection) + * @op: a `GtkPrintOperation` * @support_selection: %TRUE to support selection * - * Sets whether selection is supported by #GtkPrintOperation. + * Sets whether selection is supported by `GtkPrintOperation`. */ void gtk_print_operation_set_support_selection (GtkPrintOperation *op, @@ -3168,11 +3206,11 @@ gtk_print_operation_set_support_selection (GtkPrintOperation *op, } /** - * gtk_print_operation_get_support_selection: - * @op: a #GtkPrintOperation + * gtk_print_operation_get_support_selection: (attributes org.gtk.Method.get_property=support-selection) + * @op: a `GtkPrintOperation` + * + * Gets whether the application supports print of selection * - * Gets the value of #GtkPrintOperation:support-selection property. - * * Returns: whether the application supports print of selection */ gboolean @@ -3186,15 +3224,15 @@ gtk_print_operation_get_support_selection (GtkPrintOperation *op) } /** - * gtk_print_operation_set_has_selection: - * @op: a #GtkPrintOperation + * gtk_print_operation_set_has_selection: (attributes org.gtk.Method.set_property=has-selection) + * @op: a `GtkPrintOperation` * @has_selection: %TRUE indicates that a selection exists * * Sets whether there is a selection to print. * * Application has to set number of pages to which the selection - * will draw by gtk_print_operation_set_n_pages() in a callback of - * #GtkPrintOperation::begin-print. + * will draw by [method@Gtk.PrintOperation.set_n_pages] in a handler + * for the [signal@Gtk.PrintOperation::begin-print] signal. */ void gtk_print_operation_set_has_selection (GtkPrintOperation *op, @@ -3213,11 +3251,11 @@ gtk_print_operation_set_has_selection (GtkPrintOperation *op, } /** - * gtk_print_operation_get_has_selection: - * @op: a #GtkPrintOperation + * gtk_print_operation_get_has_selection: (attributes org.gtk.Method.get_property=has-selection) + * @op: a `GtkPrintOperation` + * + * Gets whether there is a selection. * - * Gets the value of #GtkPrintOperation:has-selection property. - * * Returns: whether there is a selection */ gboolean @@ -3231,21 +3269,22 @@ gtk_print_operation_get_has_selection (GtkPrintOperation *op) } /** - * gtk_print_operation_get_n_pages_to_print: - * @op: a #GtkPrintOperation + * gtk_print_operation_get_n_pages_to_print: (attributes org.gtk.Method.get_property=n-pages-to-print) + * @op: a `GtkPrintOperation` * * Returns the number of pages that will be printed. * * Note that this value is set during print preparation phase * (%GTK_PRINT_STATUS_PREPARING), so this function should never be * called before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). - * You can connect to the #GtkPrintOperation::status-changed signal - * and call gtk_print_operation_get_n_pages_to_print() when + * You can connect to the [signal@Gtk.PrintOperation::status-changed] + * signal and call gtk_print_operation_get_n_pages_to_print() when * print status is %GTK_PRINT_STATUS_GENERATING_DATA. + * * This is typically used to track the progress of print operation. * * Returns: the number of pages that will be printed - **/ + */ int gtk_print_operation_get_n_pages_to_print (GtkPrintOperation *op) { diff --git a/gtk/gtkprintoperation.h b/gtk/gtkprintoperation.h index 87085646d5..94d6dddbf4 100644 --- a/gtk/gtkprintoperation.h +++ b/gtk/gtkprintoperation.h @@ -88,7 +88,9 @@ typedef enum { * @GTK_PRINT_OPERATION_RESULT_IN_PROGRESS: The print operation is not complete * yet. This value will only be returned when running asynchronously. * - * A value of this type is returned by gtk_print_operation_run(). + * The result of a print operation. + * + * A value of this type is returned by [method@Gtk.PrintOperation.run]. */ typedef enum { GTK_PRINT_OPERATION_RESULT_ERROR, @@ -106,8 +108,9 @@ typedef enum { * @GTK_PRINT_OPERATION_ACTION_EXPORT: Export to a file. This requires * the export-filename property to be set. * - * The @action parameter to gtk_print_operation_run() - * determines what action the print operation should perform. + * Determines what action the print operation should perform. + * + * A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. */ typedef enum { GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, -- 2.30.2